On Incoming Message

Plugin: Telegram | Mode: Listen

Respond to incoming Telegram messages in a variety of ways.

Settings

Telegram Account

The Telegram account, which waits and responds to incoming messages.

chat

The chat with a player or the group chat in which incoming messages are responded to.

from

Allows to specify a players or Telegram account item when On Incoming Message should listen to a message from a specific players item or account.

Only for group chats.

priority

Determines the priority of On Incoming Message if there are several listeners at the same time, for example on other paths or narrative threads of the game.

if

With if incoming messages can be checked and reacted to in various ways. You can find out more about this in Query from conditions.

else

Occurs when none of the if conditions are met. See Conditions query.

while idle

Add messages that will be sent to the chat after a certain period of time (delay) as long as none of the incoming messages are answered by if or else.

This option is useful for sending reminders or more specific messages.

delay determines the time in seconds until message is sent.

All while idle messages delays are strung together. For example, if the first while idle message has a delay of 60 seconds and the second message has a delay of 30 seconds, the second message will be sent after 90 seconds.

finally

Go to the next state when all while idle messages have been sent. Specify with delay another time delay that will be appended to the last while idle message until next state is triggered.

Conditions

With if one or more conditions can be queried. The content of the incoming message(s) is checked as long as the state (with this On Incoming Message action) is active.

Use else to specify what happens if none of the if-conditions should have matched with an incoming message.

To add conditions to if click on "add condition".

In the dropdown next to condition 1 there is now a choice between different query types.

Condition types

With the exception of contains media, the condition types are described in more detail in the Conditions chapter.

For the different types a condition applies if:

Equals

The content of the message exactly matches the or one of the texts specified here.

Contains

The message contains the or one of the texts specified here.

Contains media

The message contains media.

Select under media which media format will trigger a next state adn/or a response. Use contains any of to combine different media formats.

Select "any" to respond to any incoming message that contains a media format.

Select "downloadable" to respond to any incoming message that contains a file that can be downloaded.

With the download option incoming files can be downloaded.

Media specific data can be retrieved using the On Incoming Message action data.

Less Than / Greater Than

The message is a number whose value is Greater or Less than the value specified here.

Regular Expression

The message matches the regex specified here.

Javascript Function

The javascript function with the message as passing parameter value returns a Truthy value.

Database Query

The given mongo query finds at least one item in the given collection.

Reactions

If a condition is true, one or more of the reactions specified under the condition are triggered.

On Incoming Message allows 3 ways to react on incoming messages.

respond

Should one of the conditions occur, respond can be used to specify one (or more) response message(s) that the account will send as a reply to the sender (chat).

If you specify multiple reply messages under respond, the next reply in the list will be sent each time the condition is true.

The last reply in the list will also switch to the next state if applicable.

If more messages arrive that match the condition, no more replies will be sent.

Select "reply" under mode if the incoming message is to be quoted.

next state

If the condition is true it will trigger the next state.

If you have also specified a respond message, it will trigger the next state immediately after the response has been sent.

If you have specified several respond messages, the next state will only be triggered after the last reply has been sent. That said next state will only be triggered when the condition has been met as often as many respond messages you have specified.

If no further response is available and no next state is specified, but the condition matches again, nothing happens.

download

download allows to download files if incoming messages have been checked for media formats with contains media. The formats "photo", "image", "document", "audio", "voice", "video" and "sticker" contain media files that can be downloaded.

directory specifies under which file path the file should be saved. Relative paths (start without '/' or with './') refer to the location of the File folder of your adaptor:ex installation. Note that the file path must already exist.

Downloaded files have an automatically generated filename. You can specify your own name for the file with filename. Note that this is the name without the file extension (.jpg, .png, .wav ...). The file extension will be appended automatically, depending on the file type.

You can then access the full file path including file name in the action data download property. You can also create a local variable under variable that contains the file path.

Example:

Here the message is checked for "photo" and "image" media which are then downloaded to the Files directory under "location_scout/img/".

The filename here is variable and depends on the variables location and index. The response message contains the file path specified under the variable "latest_img". A downloaded photo could i.e. be found under ~/adaptorex/games/Tutorial/files/location_scout/img/backyard_3.jpg.

Action data

On Incoming Message stores different information depending on the message type that was received.

You can access the data via the action data variable. Use for example:

[[state.MyState.onMessage_1.text]]

to access the last received message text of the top On Incoming Message action in the state MyState.

Origin data

The following properties are always contained in On Incoming Message action data:

id

The Telegram id of the incoming message.

date

The date and time when the message was sent to the chat.

from_id

The Telegram id of the user who sent the message (to the chat). Corresponds to the id specified in the corresponding item in the 'players' collection under telegram.id.

to_id

The Telegram id of the account or bot listening for incoming messages.

peer_type

The type of chat in which incoming messages are listened to. In a single chat with a player, peer_type equls user. In a group chat, peer_type equals chat.

peer

The Telegram id of the individual or group chat the message was sent to.

If it is a single chat (peer_type is user) peer == from_id.

If it is a group chat (peer_type is chat) peer is the id of the chat and corresponds to the telegram.id of the item in the 'chats' collection that is specified as chat in the On Incoming Message.

Variable data

Some action data is only available if the last incoming message is a specific message type. match is only available if one of the if conditions matched the last message received.

text

The text of the incoming text message. If media messages contain a caption it will also be stored as text.

match

The text or part of the text to which the if condition applied.

media

The media type of the incoming message. Can take one of the following values:

"photo", "image", "document", "audio", "voice", "video", "sticker", "geo", "geolive", "contact", "poll", "webpage", "venue", "game", "dice" or "invoice".

Some media messages store additional values in the action data (see below).

download

The file path of the downloaded media file. See download.

first_name

The first name specification of the received "contact" media message.

last_name

The last name specification of the received "contact" media message.

phone

The phone number specification of the received "contact" media message.

contact_id

The Telegram id specification of the received "contact" media message.

lat

The longitude (latitude) specification of the received "geo", "geolive" or "venue" media message.

long

The latitude (longitude) specification of the received "geo", "geolive" or "venue" media message.

title

The name of the location of the received "venue" media message.

address

The address of the location, of the received "venue" media message.

provider

The provider of the location, of the received "venue" media message.

venue_id

The Telegram id of the venue, of the received "venue" media message.

venue_type

The category of the venue, of the received "venue" media message.

value

The dice value of the received "dice" media message.

emoticon

The used emoticon of the received "dice" media message.